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Abstract. SAIL, a high-level ALGOL language for the PDF- 10, is 
extended to opciate under the TENEX timesharing system without 
executing DEC system calls. A large set of TEN EX -oriented 
runtime routines are added to allow complete access to TENEX. 
The emphasis is on compatibility of programs across time-sharing 
systems and integrity of the language. 


The research reported here was supported by the Jet Propulsion Laboratory 
under contract 953857 to Stanford University. This report serves both as 
documentation for TENEX SAIL and as the final report to the Jet Propulsion 
Laboratory. 
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/ Innoliudion 

This rc|ioiis on the modifications provided to the SAIL system (see Fridman, Swinehart and 
Sproull. VanI.ehn) to allow its use on the TENEX timesharing system. The leader is assumed to 
have some familiarity with the SAIL manual [?]. the PDP-IO reference manual [I], and the 
TENEX JSYS manual [2], 

An effort has been made to maintain maximum compatibility with the philosophy of the 
SAIL language as it luns at the Stanford Artificial Intelligence Laboratory (SU-AI), and at the 
same time to extend the utility and efficiency of SAIL to the TENEX timesharing system. 

DEC-SAIL (as we shall refer to the SAIL implemented for the DEC system) allows the user 
close contact with the DEC timesharing system. TENEX-SAIL likewise has a complete set of 
TENEX oriented loutines. Routines that are named after a JSYS (e.g., GTJFN) generally just 
execute that JSYS, although sometimes it is necessary to do a bit more for the sake of clarity. 
Several routine.s (e g.. OPF.NKILE and INDEX FILE) are a bit higher level than JSYSes, and allow 
the user to avoid TENEX bit-twiddling for the ccmimon operations For data transfer roi. tines, the 
emphasis has been on presorviiig the syntax and semantics of the old loutiiies, foi example 
INPUT, ARRYOUT. These routines are closely related to the data types available in the SAIL 
language. 

Routines maiked with a 1" in the index are oiiented to the DEC system and arc included in 
TENEX SAIL for compatibility. 

Routines that are named after a JSYS (and hence do not necessarily peifoim an exact, logical 
function) are marked with an V in the index. 

For compatibility with old programs, the routines LOOKUP, ENTER, RELEASE et al. have 
been implementi?d without calliiiy; the IO-!>0 emulator, and are described in Section ?. Wc have run 
a large numbei of old DEC-style programs on TENE?\-SAIL without much modification using 
these TENEXited loutines. 

Programs can use the DEC style and TENEX style routines together with few problems. For 
example, one might open a file with OPENFILE, do a magtape operation with MTAPE, and close 
the file with RELEASE. 

The compiler has also been completed, and the entire set of changes has been made into the 
master source files at the Stanford Al Lab. Thus, users will be able to depend on the immediate 
availability of new SAIL features in the TENEX version. For a drsctipiion of the command 
language changes see Section 2. 
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2./ The Soutff Coilf 

The intcnl of TENEX SAIL is to make basically no changes in the stitictuie of the language. 
Thus, all features are the same across systems. Source code differences are limited to: 

(1) STARTICODE and OJUICKICODE: the DEC uiio’s (CALLI, LOOKUP etc.) are not 
available in TENEX SAIL. In their place are i‘'e JSYSes. Each TENEX site can easily construct 
its own )SYS table from the standard TENEX file <SUBSYS>STENEX.M AC (or .FAI) using a 
utility p:ogram M AKT AB.TNX. Details of this are (to be) in TELLEM, the iinplementer's guide. 

(2) REOJJIRE .SOURCE'FILE: the name of the SOURCEIFILE may he either a TENEX 
file descriptor m a p.seiiclo DF.C descriptor, re., any of the following: 

<SmrH>F000000Ci.EtAZ;3 

FOOOriflOn.RAZISn.lTH) 

FOOCiaOClO.BAZ:3(Sn. ITH) 

If the source'file is not found, the user can give the name from the terminal 

(?) RE<;HJIRE LOADIMODULE and RE<;>LJIRE LIBRARY specifications. Note that the 
LOADIMODULE and LIBRARY names must be passed to the loader In compatibility format, 
and hence the name field must be limited to six characters, and the extension field to 3. (The 
extension is usually .RED 

For the directory (or PPN) field, most TENEX sites have the strange BBN convention that 
the PPN field is of the form 

(0.DIRNO) 

where DIRNO is the number of the user's directory. Rather than perpetuate this error, TENEX 
SAIL translates the directory (or PPN field) into the number to be passed to the loader. Hence, 

<SmTH-nELFlL 

RELFILlSn.lTHl 

arc pa.ssed to the loader with the PPN field converted to the directory numbei. 

A few sites (e.g., IMSSS) have used sixbit PPN's v,^ith their 10/50 emulator, so that DEC 
cusps do a reasonable thing. For these sites, TENEX SAIL also does the right thing, under 
conditional compilation of the .ources. 

(4) The additional runtime routines described in this document are defined to the compiler 
ill TENEX SAIL. For those users desiring to write programs that conditionally compile according 
to whether or not the site is a TENEX installation, i^ome compile-time test such as 

IFC NOT DECLARATION(GTJFN) THENC 
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will work, since CTJFN is not defined in DEC SAIL. 


2.2 ComfiiUr Command Language 

The command language to the compiler is the most different thing about TENEX SAIL. It 
has been redesigned to look like a DBN style TENEX program. 

When you say 

•SAIL 

it prints back 

TENEX SAIL 8.1 1-10-75 (? for help) 


« 

The "S. r is the version number and it is followed by the compiler creation date. 

The asterisk is the top command level. Two asterisks are for subcommand level. 

At any point that TENEX SAIL requests a command or subcommand, the following are 

legal: 

7 options available at this level 

contro I -Q 

quit 

contro I -U 

restar t 

A command is basically a list of files to be compiled as a concatenated souice stream. File name 
recognition is available, and the default extension is SAL 

Devices available are TTY:, DSK: and DTAn:. Other devices do not currently work in the 
compiler (although they work in the runtime routines described later.) Device names are NOT 
"sticky", as they are in DEC SAIL, and the default device is always DSK-. If the device is TTY:, 
then a bare control-Z terminates input. Editing is available with control-X (delete the current line) 
control-R (retype the cm retit line) and either control-A or rubout (delete a character). 

The assumption Is made that the user wants to compile his file(s) into a .REL file with the 
same name as the first file. (Note that the standard DEC cusp specification 

F(X)-F00 

is usually redundant.) If the user begins his command with a left arrow, no binary file is made. 
The name of the .REL file can be changed by a subcommand. Also, the listing file and the 
switches are subcommands. 
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The following is a BNF definition of the command language, with the semantics following 
the semicolon. <FILE> is a TENEX file specification (done by CTJFN with recognition), and <cr> 
IS a carriage return. 


<C 0 mAND>n- <FlLELIST.«<cr> 
<C 0 f 1 f 1 AND>ii- <FILCLIST>,<cr> 
<C 0 nnAN 0 >it- <FILELIST>^ 

<COnnAND>ii- <FILELIST>.- 

<COnnAND>ii- *-<FILELIST> 


I compile files in <FILELIST> 
; compile, subcommand mode 
I compile, load uith DDT 
t i f ava liable 

(Compile, subcommand, load 
iui th DDT i f avai table 
(Compile, no .REL file 


<FILE!IST>((- <FILE> 
<FILElIST>((- <FILE>.<FILELIST> 


After giving the command, if subcommand level was requested, the compiler prints 

»« 

to indicate subcommand level The subcommand syntax is 


<SUB>( ( ■ <cr> 
<SUB>i(« <control-R> 
<SUB>: : ■ <control-L> 
<SUB>t(- / <SUITCH> 
Valid su itches are: 


(bare carriage return to 
(Start compilation 
( control -R — .REL file 
(Specification via CTJFN 
(.LST specification to CTJFN 

(some suitch 


G 

T 

R 

C 

0 

P 

Q 

H 

I 

K 

<Nun>a 

<Nun>s 

<Nun>F 


load after compilation, exiting to the EXEC 
load uith DDT 
double parse stack 

cref listing (listing filename must be specified first!!) 
double define pdl 
double sgstem |idl 
double string pdl 

sharable compilation (default on TENEX) 

non- shar able compilation 

Kount feature 

BAIL features 

string space 

I i St ing format 


(See Sec. 19.3 of ( 3 ) for a more detailed 
description of these snitches.] 


Additional debugging features for the compiler hacker are available as subcommands if the 
compiler is a debugging version. 
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Loading SAIL Programs 

Tlie loader interfaces are available at IMSSS, and available at other TLNEX sites provided 
the TMPCOR feature exists in the emulator. 

To load a SAIL program, the mam trick is to load the "SAILOW" file first. In TENEX. 'ne 
name of this file (to the loader) is "SYS;LOWTSA.REL", where "SYS;" is whatever ci.iectory the 
emulator recognizes as such (this is now usually <SUBSYS>). Thus, the following are so Tie 
reasonable command strings to LOADER (where "I" is an altmode); 

SYS I LOUISA, DSKiFOOl tioad protira* FOO 

SYSiLOUTSA.DSKiFOO.BAZI ;load programs FOO and BAZ 

SYSiLOUTSA./TDSKiFOOl tioad uith DDT 


At sites where LINKiO is available, (such ,is SUMEX and PARC.) it is strongly 
recommended to load with LINK lO. A s.Tmplc command sequence would be: 


eLlNiae 
*SYS I LOUISA 
♦OSICiFOO 
»/G 


{load crucial file first!! 
; program foo 
;eKi t to the EXEC 


LINKIO is consideiably faster than LOADER; further, BBN has appaiently straightened out the 
problems of the M.iie of the core image at the end of the loading process in LINKIO running on 
version 1.31 of TENEX. In LOADER, there are several hassles pertaining to the state of the PSI 
system and the emulator. Waining: LINKIO may not work with some versions of DEC 
FORTRAN if the SAIL program calls FORTRAN subroutines. 


2.4 Editor Intfrjacts 

Interfaces to all editors are in the IMSSS version only. "T" gets the "best" editor for 
whatever terminal you are on, "E" gets STOPGAP. At IMSSS, the editor interfaces are currently 
limited to 6-character names and 3-character extensions, with no version specification. 


2.5 Compiler Error Handling 

The error handler works as in DEC SAIL. Logging features are available, with the default 
name FILE.LOG, where FILE is the (first) source name. In specifying the log file name fiom ti.e 
terminal, CTJFN is used with recognition. 

The Stanford escape ! interrupt (to reset the error handler) is implemented with a TENEX 
pseudo-interrupt on the character control-H. (Conttol-I would have been a bad choice since that 
character is a TAB.) Typing a contiol-H resets the error handler when it has been put into au‘o* 
continue mode. 
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} OEC-StyU finntinf Routines 

The drjLi^n cntenon of the new routines is to allow "standard" |jrrn.iams written for the DEC 
I/O to run oi^ TENFX-SAIL without the rmulatnr. The routines drsciibed in this section are the 
old routines. Refer to the SAIL manual [?] for a complete description of these routines as they 
originally worked. 

Some routines (e.g., LOOKUP) return error numbers. In TENEX SAIL. these error 
numbers are the TENEX error numbers (in the sense of the TRSTR JSYS) rather than the DEC 
error numbeis. The jiisiifiraiiun for this is that (I) tew SAIL programs check, for example, the 
nature of a LOOKUP eimr (illrf;.al PPN. illegal file, file being modified. eic\ and (2) any program 
that was examining infornvation that closely wmilrl leqiine lecoding using the TENEX error 
numbers, which apply more sensibly to a job running on TENEX. 

The r.Al.l. louiine descrilrecl on p.age 8 is a somewhat special fiinriion. in that in DEC- 
SAIL It IS intended to provide ^pecnl system calls. Wc have implemented in TENEX-SAIL those 
CALLS that are most likely to be used in .r user SAIL program dating from the pcricxl of time that 
SAIL has been avail.ible at IMSSS. 

QPr.mHAN:tyEr.MOltE.IBVF.OBUF.nCOUNT.<9HnK.KEOF) 

In the DEC system, the MOl>E parameter indicates which of the data mcKles are to be used. 
Typical choices aie: 0 for tharacteis. 'H for ?6-bit words, 'P for clump mcH,1e. In TENEX. this 
parameter is mostly ignoied. In TENEX it is not. for example, possible to do clump mcxle I/O to 
the dsk, nor is it possible to do character mode I/O to the magtape. A case that is not ignored: 
dump mode I/O to the dcctape gives dump mode as on the DEC system, wherein one can ignore 
the directory on the tape. 

In the DEC .<ystem. the !BUF and OBUF parameters specify the number of buffers desired 
for input and output ic'^pi'ctively. Since buffering is handled differently in TENEX, these are 
used only to indicate whethn input oi output is desired. 

Currently, the above two facts create an incompatibility, which occurs wh^'u a device is 
opened in dump mode with nn buffers specified and then a data transfer aitempied without either 
a LOOKUP or ENTER. This bug will be corrected; until it is. the usei should see the 
OPENFILE routine, which is intended to icpiace OPEN, LOOKUP, and ENTER for file 
accessing in TENEX SAIL. 

lOO\a\?{CHAN:FILE",nFLAC) 

For the "FILE" parameter. LOOKUP. ENTER. AND RENAME in TENEX-SAIL all 
accept either DEC or TENEX file s|>ecification, as does REQUIRE SOURCEIFILE (see Section 
2.1 above). 

ENTER(C///(/S/."f/L£".»*fL/<C) 

Simulates the ENTER function. 


RZtiAME{CHAN:NEW!NAME".PROTECTION.fiFLAG) 
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The PROTECTION feature docs not work. Note that TENEN provides extensive 
protection features winch are accessible thioiigh the CTFDB and CHFDD routines. 

USETI(CAy/f\‘.Oi.tX/^) 

On TENEX. there is only one file pointn for both input and output; hence, USETI and 
USETO are the same fiinciion in TENEX SAIL USETI (or USETO) only works on those 
devices wheie the SFP TR JSYS works Currently, this is only the disk in TENEX. A USETI to a 
dectape causes the blixk on the i.spr to bo set via the MTOPR JSYS, which is not necessarily what 
Is intendetl on the r»KC'. system 

In DEC. SAIL, the .action of USETI could be .somewhat confusing, since the effect of the 
USETI only take* pl.ico wiien the next input fiom the syston is requested. Thus, old data .still in 
buffers can be input beloie ibe i’if»*ct uf the USET! Ml TENFX SAIL !ias r.inclom input and 
output more completely implemeiiti'd. Hi-nce, USETI and USETO i.“.ke place immediately, with 
the next input or output reierencing BLOCK. 

See iSiv discussion oi random I/O in section Subsection S.?, noting that 
USETI (LUAN.dLCiCId is e.]uivalen( to SUflPTR (CMAN. (BLOTK-I U12S). 

VH£TO{( HAN MOCK) 

TENEX has only one file pointer (whuias the DEC system in iii iit of its incarnations has 
two). Thus, USETO is the same function in TENEX SAIL as USETI. 

CLOSmCHAN) 


Simulates the CLOSIN function. 


ClOSOiCHAN) 


Simulates the CLOSO funrtion. 

CIOHUCHAN) 

Does both a CLtTSIN and a CLOSO. 

RELEA.SE(C7//fA/) 

Simulates the RELEASE function. 

MTAPE(C7//fA/.fUA/CT/OA/) 

FUNCTION IS (lerformed on CHAN, accoiding to the following code: 


1 
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FUNCTION Operation performed 

"A" Advance past one tape mark (or file) 

"B" Backspace past one tape mark 

"E" Write tape mark 

"F" Advance nne I ecoiri 

"R" Backspace one I ccord 

"S" Wiite ?• inches (if l>lank tape 

“T" Advance to logical riicl of tape 

"U" Rewind and unload 

"W" Rewind tape lo load point 

In the ciinent DEC version of SAIL, another mode has heen implemented: "I" for IBM-compatible 
mode. Since this is not a .standard TENEX feature, it is not available. 

The user should also .see the MTOPR routine, which does the TENEX MTOPR )SYS in 
its full generality. In particular, some DECTAPE operations are performed with MTOPR. 

The user is warned that there are serious limitations in TENEX regarding magtapes. While 
TENEX IS supposed to have dcvice independent I/O, the magtape code in TENEX (as of v. I-3I) 
is minimal, allowing only dump mode transfers Further, end of file markers must be written 
explicitly, and it is sometimes necessary to do an MTOPR operation 0 to reset the magtape status 
bits. 


TENEX SAIL has been designed to handle some of these things in a way that makes 
features available on a standard DEC system available in a transparent way. For example, string 
input and output functions work, with SAIL assuming l2S-word records on the tape. ARRYIN 
and ARRYOUT cause the DUMPI and DUMPO JSYSes to be executed for the specified word 
counts. Closing a magiape fik> upon for writing will cause two EOF’s to be written, and one record 
backspaced. Status hits air cleared automatically. Thus, sequential leads and writes will work 
pretty much as they did on a DEC. sy.'.tem. The user who wants to write magtape code for 
operations other than ihe above is hereby warned that the TENEX magtape code is ftought with 
peril. TENEX .SAIL certainly allows full access to TENEX in this regard, however. 

NEWfCHAN ^CETCUAN 

GETCHAN In TENEX collects a bug still present in DEC-SAIL, namely, that while 
GETCHAN returns a channel thought to be available, it does nut reserve that channel, and hence 
successive GETCHANs without inteivening OPENs will get the same channel. In TENEX-SAIL. 
GETCHAN reserves the channel until an OPEN or RELEASE is performed. 

REAUJFN - CVJFN(C7//4/;) 

This IS an important function conceptually, although you may never need it. SAIL uses 
channels for both the DEC style I/O and the TENEX style I/O. For most purposes, you do not 
need to know what the TENEX JFN "really" is, since aH the routines in TENEX-SAIL use the 
channel numbers. But, if you really want to have the 36-bit JFN (including flags in the left half), 
this function will provide that information. 
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RESULT - CALUACCUMULATORfARCUMENTrFUNCTlON’') 


The CALL function in SAIL was designed to call whichever CALLIs were defined in the 
particular time-sharing system. The following CALLIs are supported <in pure TEN EX coding) in 
the TENEX-SAIL. Any othrr call will give a non-fatal SAIL error, from which continuation is> 
possible. 


Implemented CALLIs; 


EXIT 

DATE 

LonnijT 

TIMER 

MSTiriE 

OETPPN 

RUNT in 

PJOD 

RUN 


In addition, the IMSSS version has the following special CALLIs defined. 


OATSAV 
PUriNF 
GET INF 
RANDOn 

It is believed that this includes most of the CALLIs likely to be made from a SAIL program. 


4 Obtaining ami Rdrasing Filti 

The routines in this section replace the DEC routines OPEN, LOOKUP, ENTER and 
RELEASE. They allow these opeiaiions to be done, relative to the SAIL data structures, with 
much of the full generality of TEN EX. 


The following functions are the standard tools to reach for in doing I/O. The new user to 


TENEX SAIL will find that these .satisfy most SAIL and TENEX needs. 

OPENFILE 

Obtain a file 

CFILE 

Release a file 

SET INPUT 

Set parameters for input 

INPUT 

Read in a string 

OUT 

Ur i te a string 

ARRYIN 

Read in an arrag (36-bit uords) 

ARRYOUT 

Urite an array 

JFNS 

Read file name 
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4.1 Main File Opening Routines 

The mam procedure is OPENFILE. In terms of TENEX, OPENFILE does a CTJFN and 
OPENF. Additional routines provide support to OPENFILE including SETINPUT, SETPL, 
INDEXFILE. and CFILE 


CHAN - OPENFILF.rA/WA/f", ’•OPTIONS") 


NAME IS the name of the file to he opened. If it is null, then OPENFILE goes to the user's 
console for the filenaine, using TENEX filename recognition. 

CHAN, the value oi the call, is a SAIL channel number. Note that the channel number is 
not necessarily the same as the TENEX JEN (although it probably is). If you really need to know 
the JFN, use CVJFN. All TENEX SAIL functions accept a channel number, not a JFN. 
(Exception; SETCHAN, for hackers only.) 


OPTIONS IS a string of ontions available to the user. Legal options are: 


Read or iirite; 

R react 

U nr i ft 

A append 

Version numbering, old-nen; 

0 o I cl f i I ? 

N neii file 

T temper anj file 

* index nith INDEXFILE routine 

Independent bits to he set: 


C 

D 

H 


rec|uire confirmation 
iemore deletocl bit 
"thaiifd" access 


Error handling; 

E return errors to user in the external 

integer fskipl. TENEX error codes are used. 
(CHAN ui I I be released in this case.) 


OPENFILE does a CTJFN followed by a OPENF. If some error occurs with the file, an 
error message is printed by OPENFILE. and an attempt is made to obtain a file name, from the 
user's console. This internal handling of errors can be avoided with the "E" mode. If an error 
occurs when the "E" mcxle was set. OPENFILE will return -I to the user, and the TENEX error 
code will be put into EXTERNAL INTEGER Iskipf. Examples of the OPENFILE routine follow. 
To write on a file, the name of which is specified from the terminal: 


BEGIN 

INTEGER JFN; 

OUTSTRCFILE NAME* ")s 

JFN <- OPENFILE (NULL, "UClt COfinENT unite, confirm name; 
OUT (JFN, "text 

")i 

CFILEUFN); COriMENT close the file; 

END; 


To read lines from a file: 
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BEGIN 
STRING Si 

INTEGER JFN, BRCIIAR. EOF; 
SETnREAK(l.‘12.’15<i*H."lN"); 
OUTSTRI" INPUT FILE* "): 

JFN <- OPENFILE<MllLL."nCO“); 
SE T I NPU T ( JF N . . BRCHAR . EOF ) ; 
DO 

BEGIN 

S <- INPUT (JFN, 1); 
END UNTIL EOF; 

CFILE(JFN); 

END; 


SLTINPlIT(C7V/4^. nCOVNT, nBRCHAR, nEOF) 

This routine relates to the functions of the last three arguments of the OPEN function in 
DEC-SAIL. When the user wishes to use the COUNT, BRCHAR, and EOF features of the input 
routines, SETINPUT will .issociate the reference locations COUNT, BRCHAR, and EOF with the 
input from CHAN. The INPUT function (see Section 5.2) uses 200 as the default value of 
COUNT if no location has hecn associated with CHAN. 

As an added convenience, all I/O transfer routines set hkipf to indicate end-of-file and I/O 
errors. For e.xample, on return from INPUT (see Section 5.2), !skip! will be - I if an end-of-file 
(Kcurred, a TEN EX error number if an eiror occurred, or 0 otherwise. 

SETPMf ///lA/, >^UNNUM, .^PAONUM, aSOSNUM) 

This loutine exti'iids tlie iisriiiliiess of the INPUT function in leadin':', through a file. Often, 
one wants to read a file, Init lie able to keep track of where one is in the file. Tins routine allows 
the user to name the vaiiables to be used by the INPUT function for counting the linefeeds (’12) 
and formfeeds (’N) seen by INPUT, as well as keeping the current SOS line number, if any. 
SETPL inilialires all three variables to 0. Each time a formfeed is seen, LINNUA1 is set to 0, and 
PACNUM is incremented. Hence, LIN NU M is a count of the number of linefeeds seen on the 
current page, and PACNUM is the number of formfeeds seen. 

Only input with the INPUT, REALIN, or INTIN functious Is affected. In particular, 
CHARIN, and SINI do not affect these locations. CHARIN and SINl were coded for speed rather 
than flexibility. 


FOUNU.'ANOTHER.fFILE - INI)EXFILE(CW/4A/) 

This routine is useful when OPENFILE is used with the V option, which indexes through 
many files. (This is the way that the "DIRECTORY" command works in TENEX.) INDEXFILE 
returns TRUE as long as another file can be found on CHAN. 

The following SAIL statements illustrate the use of OPENFILE, SETINPUT, and 
INDEXFILE. 
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JFN - OPENFILEr<JONCS>*.SAI;*"."RO»"): 

COMIIENT Re^itl nil of Jones’s SAIL procirnms.j 
SETINPLIT (JEN. 200,0, EOF); 

DO 

BEGIN " INDEX" 

DO 

BEGIN "READ FILE" 

STRING S; 

S - INPUT (JFN, BREAK 'TABLE I; 

COMMENT process . . . ; 

END "READ FILL" UNTIL EOF; 

END "INDEX" UNTIL NOT INDEXFILE(JFN) ; 


For those fnmilirn with the DEC system, the "s" option takes the |ilace of reading the MFD 
and the UFD’s. INDEXFILE clears the EOF. LINNUM, SOSNUM, and PAGNVM variables if 
these have been set by SETINPUT and SETPL. 


4.2 Auxiliaty File Opening Routines 

CHAN - CTJFN(T/L£A(/IA/£".fL/(GS) 

Does a CTJFN. If FILEN 4ME is nori-iuill, it is the filename, otherwise the loutine goes to 
the user’s console for a file. FL.-IOS are used for accumulator I, and any error code is returned in 
hkip!. The value of the c.ill is the CHAN, if obtained. 

Ordinarily, this routine will not be needed, since the more facile routine OPENFILE is 
available. (CTJFN, OPENF, GNJFN, CLOSF. RLJFN, and DVCHR are all in this category of 
being included only for cornplrtonrss, and are not necessary for most I/O needs.) 

MORE.'FILES - CNJFN(C/y/lA/) 

Does the GNJFN JSYh>. Note that a file that is open cannot have GNJFN applied to it. 
The user will usually find that the INDEXFILE, which executes the GNJFN JSYS among others, 
is actually the logical function he desires. The exception is if files are being indexed without 
actually being opened (i.e.. without an OPENF JSYS), which is a sensible way of |)erforming some 
operations, such as counting the number of files in a group. 

CHAN -CTJFNL 

{''ORmTR\FLACSJFN!JFN:OE\''‘.’'DIR’'rNAM''. 

"EXT’',’'P ROT"," ACC 01 >Nr.OESIREO!JF N) 
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Does the long form of the GTJFN JSYS. The arguments are put into the accumulators and 
locations in the table accepted by the long form. (See [2] for a description of the long form of 
GTJFN.) 

These argiimeiit.s aic given below, where "AC X" means an accumul.nor, and "E*\" means 
In the Nth address of the table. 


Argument 

Ulliere 

p 1 aced 

Uhcit 


"ORIGSTR" 

AC 2 


Partial or complete string 

FLAGS 

E+H 


Flags to GT.IFN 


JFNUFN 

E+1 


xnd input JFN, 

output JFN 

The 

foil on i ng 

5 tr ings 

may he do faulted 

to NULL 

"DEV" 

E+2 


device 


"DIR" 

E+3 


directory 


"NAME" 

E-iA 


name 


"EXT" 

EaS 


extension 


"PROT" 

E+e. 


protect ion 


"ACCOUNT" 

E+7 


account 


DESIREDUFN 

E+’10 


desired JFN i f 

Bll on 


It should be noted th.it GTJFNL will not OPENF the file. See the OPENF routine. 

OVLmcn AN. FLAGS) 

Docs the OPENF JSYS on (.H AN, with FLAGS the contents ol acciimiil.itor 2. TENEX 
error codes are iTturncd in fskipf, which is 0 if no errors occurred. 

The occasion may arise lhat the iishi will lind the options in the OPENFILE routine to be 
insufficient, and will need m use rnher GTJFN or GTJFNL to get the JFN In these rases, it will 
usually be necessary to OPENF the file with this routine. 

The user should note lhat the ways in which TENEX-SAIL opens files do not always 
correspond to what would be obvious This is in pait due to the need to have all bits whenever 
the device is capable of transmitting ?6 bits, so that STOPGAP line numbers work in the INPUT 
and LINOUT functions. Rest le.sulis are obtained by opening a TTY in 7-bit mode, the DSK or 
DTA in 36-bit mode, and a magtape in ?6-bit dump inode. (Indeed other possibilities may not 
even work; for example, magtapes cannot currently be opened in mode 0 in TENEX.) 

CHAN S^TC\\kU{REAL!jFN.CTJFN!FLACS.OPENF!FLACS) 

This function should bo considered liberation from SAIL I/O. It Is provided for those who 
wish to do SAIL I/O from a JFN that is obtained from some other means than the SAIL file- 
opening routines - for example, a JFN passed fiom a superior fork. 

REALfJFN IS a ?C>-bii JFN (or JFN substitute, such as a Teletype number), 
CTJFNfFLAOS and OPENFIFLAGS are the flags that should be ircoiih'd de.scribing how the 
GTJFN and OPENF were accomplished. REALIJFN need not be opfii. The value returned by 
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SETCHAN IS a TENEX SAIL channel number, which should be used for subsequent TENEX 
SAIL I/O. SETCHAN is the only function in TENEX SAIL that takes an actual JFN as an 
argument. 


4.5 File Closing Routines 


SUCCESS - CFILE(C7//<A/) 

Closes the file (CLOSF) and releases (RLFJN) the CHAN. This is the ordinary way the 
user will dispense with a file. 

Returns TRUE if CHAN leg.a| and lelcased and returns FALSE otherwise. 

CLOmCHAN) 

Does a CLOSF on CHAR. Ordinal ily the user will want to use the CFILE routine, which 
handles errors internally. The CLOSF is accomplished in such a way that CHAN is actually not 
released. 

If the device is a magr.ape open for output, then 2 end-of-file marks aie written, followed by 
a backspace. This writes a sr.'uidarri end-of-lilc on the tape. 

CLOSF therefore does nioie than its name implies. 

RLJFN(C/V/IA/) 

Does the RLJFN JSYS. Ordinarily the user will want to use the CFILE routine. 


4.4 Aiixiliaty File anil bevUt Routines 

DElViCHAN) 

Deletes file on CHAN. The file must not be open at the time, .<o you may have to do a 
CLOSF first. TENEX error codes are returned in fskifi.i, which is 0 if no errors occurred. 

NVMBERfbELETEb - blimCHAN. NV MBERIRET AIN) 

Deletes all but NV MBERIRET AIN versions of the file on CHAN, which must be 
CLOSFed first. Thus, letting NV MBERIRET AIN be 0 will delete all versions of the file, 
NUMBER, RET AIN 1 will keep only the most recent version of the file. The number of files 
actually deleted is returned as the value of the call. 

UN DELETED // /< A/) 

Undeletes the file open on CH AN. TENEX error codes are returned in fskip!, which is 0 if 
no errors occurred. 





• 
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SIZE - ^XZmCHAN) 

Gets the size in pages uf ihi’ file open on CHAN. TENEX error codes are returned in 
tikip!, which is 0 if no errors occiineil. 

"FILENAME" ^ ]VNmH AN .FLAGS) 

Returns the name of the file associated with CHAN. FLAGS are for accumulator 3 as 
described in the JSYS manual. 0 is the leasonable default for FLAGS. 

STATUS *- CTHTSiCHAN) 

Gets the file status with the CTSTS JSYS. 

WARNING: The results of this call are not necessarily appropriate for determining the end- 
of-file if the file is being page-mapped by SAIL. If you want to check for end-of-file, examine the 
EOF variable instead. See SETINPUT. 

STSTSfCH /< A/, A/ £IV ./Sr /fn/5 ) 

Sets the status of file on CHAN to NEWfSTATUS. TENEX error codes are returned in 
fskipL which is 0 if no errors occuiicd. 

SUCCESS - RNAMF(£X/ST//V^;C;H,^A^.A/£IV(/y/fAf) 

Dors the RNAMF JSYS. rrn.ammg the file on EXISTINGCH AN to the name of the 
(vestigal) flic on NEW'C.II AN. It is necessary for the user to CLOSF EXISTINGCH AN before 
this operation, and then OPENF .igain afterwards. 

The routine RENAME from the DEC-stylc routines is sometimes more convenient to use 
than RNAMF. since it pcitorms the GTJKN and OPENFs nccc.ssary for the renaming operation. 
However, the actual JFN associated with CHAN is of course changed by RENAME. 

SUCCESS - ASND(D£K/C£) 

DEVICE (a TENEX device descriptor) is assigned to the user. TENEX error codes are 
returned in hklp!, which is 0 if no errors occurred. 

SUCCESS - ^lLD{DEl'ICE!DESCRIPTOR) 

DEVICE is deassigneil. If DEVICE is - I, then all devices assigned to the job are deassigned. 
TENEX error codes are returned in fskipf, which is 0 if no errors occuircd. 

DEV/ST. AT - CDHrfiiCHAN.MVORDfCOUNT) 

The status of the device mi CHAN is letuined in DEV/ST AT and the contents of AC 3 (the 
word count) is returned in reference variable WORD.'COU NT. 


SDHTfUCH AN, NEW .'STATUS) 
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The status nf the deviro on CHAN is changed to NEWfST ATVS. Remark; some magtape 
statuses (such as EOF) arc not. .is ono would suspect, set by this JSYS. but rather by the MTOPR 
JSYS. Ordinarily, the SAIL runtime system takes care of this, but it is worth mentioning, since so 
many users have run into this poorly documrniccl fact about TENEX. 

DEl'KEfDESIONATOR - STDEV("f)£r/C£/A//fA/£") 

A string (such as “DTAn") is converted to a DEVICE!l)ESION ATOR. Warning: TTNEX 
does not accept lower rase characters as being equivalent to upper case characters on the STDEV 
JSYS (although it does on CTJFN for example.) TENEX error ccxics are returneo in fskipf, which 
is 0 if no errors occurred. 

"DEl'ICE/NAME" - DEVHTiDElHCEfOESIGN ATOR) 

Returns the string name of DEl'lCEfOESICN ATOR. 

DEl'ICEfTYPE *- DlVTYPEiCHAN) 

Returns (via the DVCHR JSYS) the device type of the device open on CH AN. The more 
general DVCHR call is also implemented (below). 

DEIHCE'CHAR ACT ERISTICS - DVC:HR(C.*y ?) 

Does the DEVCHR JSYS. returning the flags from AC2 as the value of the call, and ACI 
and ACS get the contents of ac's I and ?. 

CTFDn(f.7//<A/,- REFERENCE INTEGER ARRAY BUF) 

Entire FDB of CHAN is read into BVF. .No bounds checking, so BUF should be at least '25 

words. 


CIIFDB(C/Vy<A/. DISPLACEMENT. MASK.CHANCEDfBITS) 

Does the CHFDB JSYS on CHAN, with DISPLACEMENT, MASK, and 
CH ANCEDIBITS as described in (2). 

mO?mH AN FUNCTION VALVE) 

Does the MTOPR JSYS. The user may find the DEC-style MTAPE function more 
comfortable. FUNCTION goes into accumulator 2, and VALUE goes into accumulator 3 

BKJFN(CW/(A/) 

Does the BKJFN JSYS on CH AN. TENEX error codes are returned in fskifif, which is 0 if 
no errors occurred. Not intended for ordinary use. 

BYTE-SIZE - RFBSZfCH/IA/) 

Reads the byte-size of the file open on CHAN. Not intended for normal use. 
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5 Data Ttansjrr RotiliniS 

The routines descnlx d in tins section ilo data transfers. For the most i^art, these routines are 
the same syntnciically and srin.iiitically as the loutines in DEC-SAIL. 

One improvement in TENE\ SAIL is that characters and words can bo mixed in reading or 
writing to a file, provided the file is on the disk. Such I/O is called >Uua mixfil 110. 

The following, inteipietaiion is given to data mixed I/O. There is one lo^pcal character 
pointer into the file. When a character is read or written, it accesses the byte pointed to by the 
pointer. There is only one pointer foi both input and output. When a word is read or written, the 
next full word position iii the file is accessed. 

See below for reading and changing this pointer. This feature is only available to those 
dc .'ices that support random I/O, currently only the disk. 


5./ Output Rout inn 


Cl\AROVT{CHAN. CHAR) 

Writes a single CHAR to CHAN. 

OVTiCHANrSTRINC) 

Outputs a SAIL string to the CHAN. 

UNO\.n{CHAN.\'ALVE) 

This routine has little use, but is included since it was in the DEC-SAIL. It writes an SOS 
line number on CHAN. 


WORD -WOnDmCHAN) 

Reads a word (36-bits) from the file, which must be open for !t6-bit transfers. 

WORDOllT(C7y/iA/. BYTE) 

Sends a ?6-bit BYTE to CHAN, which must be open for ?6-bit transfers. 

ARRYIN(f./y/IA/, fiLOC, COUNT) 

Reads in COUNT words into LOC from CHAN. The file should bo nprn for ?6 bit bytes for 
this to work. If the CHAN is open in TENEX DUMP mcKle (which should not bo confus^ with 
the DEC system DUMP mode), each ARRYIN or ARRYOUT specifies « .Mngle DUMPI/DUMPO 
operation. This is particularly relevant to magtape operations. 

WARNING: no array bounds checking. 
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ARRYOllT(C.//y<Af, i^LOC, COUNT) 

Writes COUNT words to CHAN starting at LCC. The file should be open in ?6-bit bytei. 


5.2 ChauKtn Input From Filn 

DEC-SAIL had the following routines for character input: 

INPUT REALIN INTIN 

TENEX-SAIL has these rnutini's, plus the routines CHAR IN (read a single character) and SINI 
(read a string upto a specified character). Also, the INPUT function can be set (using SETPL) to 
count the page and line numbers in the file. 

CHAR»-CA\ARmCHAN) 

Returns the next chaiactti from a file (open for character reading). Returns 0 if the file is at 
the end. 

’•INPUTfSTRINCr - fimiCHAN. MAX LENGTH, liRkCHAR) 

Reads in a string of chaMcters, terminated by BRKCHAR or reaching M AX LENGTH, 
whichever happens first. (It is n.amed SINI becau.^e it is like the SIN JSYS in TENEX.) 

The external integer >ikip! will be -I if call terminated for count, else it will have the 
breakcharacter, which will be the last character lead if the end-of file is encountered. 

'tN PUT !ST RING" - INI»llT(r./y/IA/. BREAKfTADLE'NUMDER) 

REAL >■ nLAimCHAN) 

INTEGER ». lNTIN(C/y/<A/) 

(For a description of INPUT. REALIN. AND INTIN see Sec TA of (3).) 

STDBRK(C///<N) 

This loutine leads in the standaid break-table file on CHAN. 


5.? Ramhm Input anil Output 

As mentioned pi .'Viously, TENEX SAIL allows the mixture of input and output from the 
same file with both characters and words being read and written For these purposes there is one 
logical character pointer to the next character to be read or written. Either reading or writing a 
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character incromrnts dial |tuiiiifr. If a read pa»e5 the end of the file, the F.OF variable in the 
SETINPUT liinctioii (or die DEC fiinctiuii OPEN) and external intege* fskipf are set to -I. If a 
write passes the end of file, then the end of file is advanced. Reading or writing a word advances 
the character pointer to the next full word in the file, where 5 ASCII characters is of course one 
word. 


When the device allows for random I/O, TENEX SAIL provides the following four logical 
functions to read and modify the character and word pointers into the file: 


RCHPTR(CHAN) 
SCHPTRILHAN. POINTER) 
RUDPTR(CHAN) 

SUDPTR (CHAN. POINTER) 


roods the choroctor pointer 
sets the ch.arocter pointer 
reads the nord pointer 
sets the nord pointer 


RCHPTR and SCHPTR rrad and change the character pointer. RWDPTR and SWDPTR read 
and change the word pointer, These functions work like RFPTR and SFPTR when the file is 
open in 7-bit size for characters or ?6-bit size for words The user should not, however, use 
RFPTR or SFPTR diie<ily. sinrr the regular TENEX pointer accessed by RFPTR and SFPTR 
will lot necrssaiily ief|«-cl liiilfeimg. 

The TENEX SAIL user is w.imed tliat data-mixed I/O and nndum I/O are not features of 
DEC. SAIL: heme, piojpains tisiiig tliese features will not be leadily transpoi table to PDP-IO sites 
using the TjFC .system 

Currently the raiuloiv featuie only works on the disk; however, they are coded so that if 
RFPTR and SFPTR aie ever extended to other devices (e.g., DEC tape), then random I/O would 
work on those devircs as well. For fastest operation on the disk, the appropriate pages of the disli 
file are mapped using the PMAP JSYS. 

There is some inefficiency associated with data mixed I/O and random I/O, since the SAIL 
runtime system has to shuflle us pointers and perhaps do PMAPs and reset the eiid-of-file pointer. 
Calls to TENEX (which represent the greatest potential overhead) are however kept to a minimum 
for fastest operation. 

The following is the list of routines that are associated with tandom I/O. The routines 
RFPTR and SFPTR are included for completeness, and should not be used by the ordinary user. 
The character pointer is accessed with RCHPTR and SCHPTR, and the word pointer is accessed 
with RWDPTR and SWDPTR. 

iHARPOINTER - RC|IPTH(C/f ><A/) 

Returns the byte that will next be .accessed by a character read or write operation, where the 
first charactei is character iiumlier 0. Illegal unless the file is on the disk. Does not change the 
state of the I/O system. TENEX error codes are returned in which is 0 it no errors 

(Kcurred. 


HAN, NEW POINTER) 


I 


Changes the byte that will next be accessed by a character read or write operation. If 
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NEW POINTER i» -I. then the iioiniei is set to the end of file. Setting the pointer beyond the end 
of the file may change the Irngili of the file if it is being written. Illegal unless the file is on the 
disk. TENF.X error codes are leiurned in hkiltf, which is 0 if no errois occurred. 

WORltPOINTER - RWDPTR(C /y/4/Sf) 

Returns the numbei nf ilie next word tint will be read or wiiiten by a word operation, 
where the first word is word number 0 Illegal unless the file is on the disk. Does not change the 
state of the I/O system. TEN EX error codes are returned in fskipf, which is 0 if no errors 
(xcurred. 

hWnVTmiUN.NEWPOINTER) 

Changes the woid that will next be accessed by a word read or write operation. If 
NEW POINTER is -I. then the pointer is set to the end of the file. Setting the pointer beyond the 
end of the file will change ihe length of the file if it is being written. Illegal unless the file it on 
the disk. TEN EX eiror coiles are letiiinerl in 'skip!, which is 0 if no errors occuired. 

SknUiCH 'IN. POINTER) 

Does the SFPTR JSY.S. Not intended for normal use. VENEX error codes are returned in 
hkip!, which IS 0 if no eiiors ucuiiietl. 

POINTER - RFPTm HAN) 

Does the RFPTR JSYS. Not intended for normal use. TENEX error codes are returned in 
hkip!, which is 0 if no errors occiiried. 


i.4 lhu<t HSK Opnnlions 

The routines DSKIN and DbKOUT do direct DSK operations in TENEX-SAIL. They 
correspond to the device PAK in the DEC system These routines relate only to the IMSSS version 
of TENEX-SAIL. 

DSKIN(AfOf)(//.£. RECNO. COUNT. nLOC) 

[IMSSS only.] 

DSKIN does direct I/O Irom the DSK (formerly device "PAK") Modules *i-7 are legal for 
everyone, other modules lequire enabled status. 

coil NT words ("<*IOnO) are read into user's coie at location LO< , from MOOULE, record 
RECNO. TENEX error codes are retiiined m Iskipf, which is 0 if no errois occurred. 
WARNING: No bounds checking is performed tc see if the LOC is a legal SAIL array. 

DSKOUT(AfOWL£. RECNO. COUNT. nLOC) 


[IMSSS only ] 


Dll<ct T)SK 0|iri.itifMU 


* t i 
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Works like DSKIN, rxcrpi ihat it writes instead of reads No bounds checking is |)erfoi med 
on the kxations being wiittcn (so ;hey may not be legal SAIL arrays). 


6 Error HarttlHrig 

When errors occur. .<on>riimes the runtime routines trap these errors themselves. This 
practice is held to a minimum, since the error itself may be infoimation that the user is interested 
in seeing. Usinlly, the routines (.is marked) put the TENEN error code m EXTERNAL 
INTEGER !skip>, which you may declare .ind examine after any call so marked. The TENEX 
error numbers don't always make good sense, but for the cases that they do, the ERSTR routine 
will print out on the user's console the message associated with that error number. 

ERSTR(£««AU/'0/?^) 

Using the F.RSTR JSY.S, lypcs out on the console the TENEX errnr .stiing associated with 
ERRNO lor fork FORK ('HiX>fHM' lor the cuirent fork). Parameters (in the sense of the ERSTR 
JSYS) are expanded. 

Types out the string ER.sTR: UNDEFINED ERROR NUMBER if something is wrong 
with your error number or fork (,ind .sets hkip! to •!). 


7 Terminal Handling 

The routines in this section really refer to terminals only in the so-called "mni-system" 
version of TENEX (planned obsolescence). The argument CHAN may be either a SAIL channe; 
number associated with a terminal, or a terminal specifier (such as '100 or '101 foi the controlling 
terminal). 


MODEfWORl) - RFMOI)(C«/fA/) 

Reads a file's mode woid. using the RFMOD JSYS. 

SFMOI)(C/f/IA/.-(C2) 

Sets a file's moile vvoid to arviimeni AC2, using the SFMOD JSYS. WARNING: some 
features, such as upper case conversion, th.it aie advertiied by BDN as being accomplished with 
the SFMOD JSYS are acui.illy acromnlished with the STPAR JSYS. 

R FCOC(f HAN.mAC2.nAC ?) 

Does RFCOC JSYS. returning values in >AC2 and AC). 

SFCOC(CHAN.AC2.AO) 
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Docs SFCOC JSYS, setting to AC2 and ACJ. 

STPARiC H AN. AC2) 

Docs the STPAR jsYS, setting to AC2. 

TERMINALfTYPE *- CTT\'P(CH AN .fiBU FFER5) 

Returns the terminal type associated with CHAN, additional values returned from 
accumulator 2 into reference parameter BUFFERS. 

STT\P{CHAN.AC2) 

Simulates terminal input on CHAN by putting AC2 in the input buffer. 

The usual SAIL routines for teletype I/O are all available in TENEX SAIL. 1 hese routines 

are: 

INCHhU ini. HRS INCHUL INCHSL INSTR IN3TRL INSTRS OUTCHR OUTSTR CLRBUF 
TTYIN TTYIN TTYIHL 

In addition, PDIN. PPjC)UT, and PSOUT have been added, although they execute exactly the 
same code as INCUR W, OUTCIIR, and OUTSTR respectively. TEN EX-SAIL sets the modes for 
teletype I/O in a way similar to the DEC system. You may examine and change those modes with 
the RFMOD, SFMOD, etc., described above. 

CHARACTER - PBTIN(J£COA/f)5) 


[IMSSS only.] 

Executes the PBTIN JSYS, with timing of SECONDS. IMSSS only. 

"INPUT.'STRING’' - INTTY 

INTTY does a TENEX-style input. (Note that INCHWL does a DEC system style line 
input, with rubont deleting one chaiacter and control U deleting the whole line.) 

At sites other than IMSSS. this routine grts a line of up to 2iX' characters using editing 
conventions siimlar to many TENEX programs. Control-X deletes the line, control-R repeats the 
current partial line, and both control- A and lubout delete a single character. Line activation is 
with an EOL. ESCAPE. control-Z or control-G The break character is not appended to the string 
returned, but is put into fskif>', which is -I if the input is terminated for overflowing the 200 
character limit. 

At IMSSS, this loutine uses the PSTIN JSYS, and accepts as many as 200 characters from 
the user's Teletype, with the standard system breakcharacters. The bieakchai acter itself is removed 
from the string, and no timing is available If the default of 200 characters is exceeded, then .fskipf 
is set to - I; otherwise, .’skip.' has the break-character. 
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S the TEN ESS AIL Tote Ima^e 

Presently, the only |):«gp-mani|Milatiun loiitiiie available is PMAP. It is cleaily desirable that 
the SAIL alkicaiioii miiiines (COROET et al.) be redesigned to take advantage of the paging 
environment, and that certain data types be added tc the SAIL language to control allocation. The 
only feature addeci is the PRESETIWITH constiuction, which is like PRELOAD!WITH except 
that the array is placed in the high segment. 

PMAP(/<C7./<C:./<C5) 

Does the PMAP JSYS, using the accumulators for the arguments. 


9 Utility TENZS System Culls 

The functions in this section do utility calls on TENEX. An effoit has been made to 
provide calls that read ami write strings which may be inconvenient for the user to perform in 
STARTICODE. It shonlil be noted that the TENEX-SAIL compilei has the TENEX JSYS 
mnemonics defined in STARTICODE These deiiriitions should not be confused with the function 
calls of the same name. 


"DATEITIME" *- ODT m(DT .FORM AT) 

The string representation of the date and time DT are returned in format specified by 
FORMAT. DT is in internal TENEX repicsentaiion. 

TENEX Defaults: 

DT -1 Current date and time 

FDRMAT -1 Format: "TUESDAY, APRIL IB, 1974 16:33:32" 

DT - IDTIM("fMr£.'r/Af£") 

DATEITIME is the date and time as a string, in some reasonable format. The internal 
TENEX representatiuii is leuniied. TENEX error codes are returned in Iskipl, which is 0 if no 
errors occurred. 


RUNNING/TIME - RmTmFORK.fsCONSOLETIME) 

The running time in milliseconds for FORK is returned, and the console connect time is 
returned in CONSOLEITIME. 


Dr ^CTAD 

The current date and time, in TENEX representation, is returned 

JOBNO *- CJINF(«L06D//^,•^»C0A/D//^/)rr>'^0) 
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The user's job number is return*^ as the value of the call. Refeiencc values are: the 
number of the logged directory (LOODIR), the connected directory (CONOIR), and the TENEX 
Teletype number (JTYNO). 

DIRECTORY /NUMDER^STDIRCDIRECTORV.DORECOGNITKIN) 

Returns the directory number associated with a string. Any problems are returned in Iskipf 
with the code. 

1 string does not match 

2 string IS ambiguous. 

Note that "DIRECTORY" MUST P.E IN UPPERCASE FOR THE STDIR JSYS. 

"DIRECTORY" - DlHfiT{DIRNO) 

Returns the string name for directory DIRNO. Any problems caus»* fskiftf to be set TRUE. 

RmPRU"PROORAM"JNCREMENT, NEW FORK) 

This docs two entirely diffeicnt things depending on whether NEWFORK is true or not. 

If NEWFORK IS true, then a new fork is createo, capabilities are transmitted, and 
PROGRAM IS run in the new lork (with the current fork suspended by a WFORK). 
INCREMENT is added to the entry vector location. 

If NEWFORK IS false, then the current fork is replaced with PROGRAM. In this case, 
RUNPRG is like the DEC RUN uuo. and hence if the INCREMENT is I, the program is started 
at the CCL address. If the routine returns at all, there was a problem with the file. 

Remember to say SAV as the PROGRAM extension. 


10 Pseiulointorui’is 

The interrupt routines in SAIL are closely associated with the special interrupt facility 
available at the Stanford Artificial Intelligence Project. In order to account for the feaiures needed 
for the SAIL language (such as the existence of processes within SAIL). a,*d to provide for the use 
of the TENEX pseudo-intorrupt system (PSI). the following decisions have been made: 

(1) The interrupt channel numbers will refer to PSI channels, not to channels in the SU-AI 
or DEC systems. See [2] for a list of these TENEX channels. 

(2) Only those interrupt functions that refer to the current TENEX fork will in general be 
provided. 

(3) The TENEX user may use the PSI system independently of the routines described 
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herein. Thus, machine code functions will generally work together with the functions described 
here. 

( 4 ) The use of the clock interrupt at SU-AI will be emulated by providing functions chat 
initiate interrupts from an iiifeiior fork. 


lO.I Immrtliate and Ihjrrrtd Intermpts 

SAIL provides two kinds of intemipts: immediate and deferred. Immediate interrupts are 
executed imniedntely. Deleiird interrupts are qued into a list of requests that are executed the 
next time a polling, point is encountered in the program. It should be remarked that a SAIL 
deferred interrupt is diffeient than a deferred interrupt in the sense of the STIW JSYS. The 
main point of the .SAIL deferred interrupt is to assure that the state of the runtime system is 
sensible when the code associated with the interrupt is executed. 

Immeiliate interrupts are liberation from SAIL, and the user is warned accordingly. In 
particular, string operations will cause horrible results if the immediate interrupt happens during 
string garbage collection. 

The following routines are the main TEN EX SAIL interrupt routines for immediate 
interrupt: 


PS I MAP 

sets up the book-keeping for a 
chonne 1 

PSI 

ENABLE 

turns on a PSI channel 


DISABLE 

turns off a PSI channel 


ATI 

associates a cont’*ol-character 
channe 1 

with a 

DTI 

turns off a given control-character 


The following example shows the ii.se of thee loutines to set up a PSI interrupt. The program is 
supposed to print out dots forever, but print "HI USER" when a control-*^ is typed. 

BEGIN 

SinPLE PROCEDURE FOO; 

OUTSTR("HI USER 
")i 

COMflENT note that only constant strings 
are accessed by FOO. : 

PSinAPIl.FOO.0,3); 

COflMFNT sets up a I eve I -3 PSI on channel 
1, and passes the addrpss of FOO to be 
executed at interrupt level.; 

ENABLE (1); COfiriENT turn on channel 1.; 

ATI (l,"Q"-*100)i 

COflflENT associates control-Q with channel 1; 

COMMENT body of pro'Tam. ; 

DO OUTCHRI".") UNTIL FALSE; 

END; 
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WARNING; Immediate iiitrirupts are asynchronous as far as the SAIL runtime system is 
concerned. While the interiiipt handlor saves and restores all accumulators, and sets up new 
interrupt-level stacks, many things may not work transparently. In particular, the creation and 
access of SAIL dynamic strings is to be avoided, since interrupting during garbage collection will 
leave the strings in a nonsensical state. 


10.2 lUjtrrtd Intawpti 

Deferred mternipts :ne s.afei than immediate ones, although somewhat more difficult to use. 
The following things r.om|ilir.,iie dcfeired internipts beyond the above example of an immediate 
interrupt. 

(1) Deferred interrupts are Jiandled by a special SAIL process called INTPRO. INTPRO 
must be sprouted by the process system. This is done by the routine INTSET. 

(2) The |«rocedure DFRINT must he passed to PSIMAP. DFRINT is executed at interrupt 
level, and it buffers the re«iuest for the deferred code. 

(3) The request for the deferred code is made by creating a special block of code, called a 
deferred interrupt calling block, and an AOBJN pointer to this block is passed as the third 
argument to PSIMAP. 

(4) Finally, the deferred interrupts must be executed This is done by including POLL 
statements in the user’s program. Since the deferred interrupts are handled by the special process 
INTPRO, POLL works just as it would for any other process, with the exception that INTPRO 
has the highest priority. POLL statements may be inserted by the REQUIRE 
POLLINCMNTERVAL statement; see [?] 

The following progiam illustrates how the.ee things can be accomplished. It is similar in 
operation to the above immediate interrupt program. 



RO 75-28 


Defeired Inteiriipts 


Page 27 


BEGIN 

PROCEDURE FOO (INTEGER I.J): 

OUTSTRCHl " & CVSII) & " " « CVSIJ) i " 

")« 

INTEGER ARRAY FOOBUIltAIs 

FOOOLKtl) *• Aj COdHENT number of uorcis involved! 

FOOBLK 121 •- 12; COMflENl number of arguments; 

FOOBLKOl - 13; 

FOOBLKIA) «- -1 L5H IS + LOCATIONIFOO) ; 

COflflENT address of FOO; 

INTSET (NEU,0) ; COfUIENT NEU returns a neu item for 

the process INTPRG; 
PSinAP(l,DFRINT.-A LSH IS ♦ LOCATION (FOOBLKlll ) .3) ; 

ENABLE (1); 

ATI (1,"Q"-’100); 

DO 

BEGIN 

OUTCHRf"."); 

POLL; 

END UNTIL FALSE; 


END; 


Now, whenever a coniiol <!^ is typed. DFRINT buffers the request, and makes INTPRO 
ready to run; then DFRINT DEBRKs (in the sense of the DEBRK JSYS) back to the interrupted 
code. At SAIL user level, the POLL statement causes the process scheduler to run INTPRO, 
where the deferred interrupt calling block (which was copied by DFRINT) is used to call FOO. 
The dots are interrupted by "HI 12 13" being printed out. 


10. > Clock Interrupts 

A feature of the SU-AI intemipt system is to interrupt on clock ticks (every l/60th of a 
second.) This interrupt happens every tick, regardless of whether the user is the running job or 
not. SAIL uses the clock interrupt to drive the process machinery via the CLKMOD routine. 
This feature is. not available on ordinary TENEX systems. (IMSSS has implemented a clock 
interrupt but BBN has declined to support it.) 

In order to facilitate the use of processes and to provide for time interrupts on standard 
TENEX installations, TENEX SAIL has the following three functions. 


PSIDISnS(PSICHAN.nSTKIE) 
PS I RUNTH (PS 1 CHAN. nST I HE ) 
KPSITiriE(PSICHAN) 


interrupt every HSTIHE milli&econds 
interrupt every flSTIHE milliseconds of runtime 
turn off timing 
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Several channels can he intei i iiptcd in this way, with different timing intervals. Currently, this is 
implemented by creating an inferior fork that dismisses, then initiates the appropriate interrupt. 
These programs run in the accumulators of the inferior fork. The following is an approximation 
of the program in the inferior fork for PSIDISMS. 


hOVE 

1. IMSTinEI 

iTiriE TO DISMISS FOR 

oisns 


;G0 AUAY 

MOVE I 

l.-l 

1 HANDLE TO SUPERIOR FORK 

MOVE 

2, Ip^irhan bit ma«kl 

I SELECTED CHANNEL 

lie 

; CAUSE AN INTERRUPT 

JRST 

UAIT 

{CONTINUE 


The followinp. is an approxim.ation of the program that luns in the inferior fork for PSIRUNTM. 


novFi 

1, MSTIME 

DlSnS FOR THIS LONG 


01 SMS 
MOVEl 

l.-l 

SW’EniOR FORK 


RUNTM 


GET TOTAL RUNTIME OF 

SUPERIOR 

CAMOE 

l.MEXfTIMtT/ 

READY 


JRST 

UAIT 

NO 


ADD! 

MOVFM 

1, MSTIME 
l.NEXTTIME 

SAVE NEXT TIME TO BE 

INTERRUPTED 

novEi 

l.-l 

SUPERIOR 


MOVE 

2. [psichan bit mask] 

SELECTED CHANNEL 


lie 


CAUSE INTERRUPT 


JRST WAIT 

CONTINUE 



Note that several different events may cause an interrupt on a given channel. For example, 
one or more control-characters may be assigned with ATI to a channel that is also being 
interrupted via a timing fork. 

The following causes the SAIL process scheduler to schedule on clock interrupts, using PSI 
channel number I. 

PSiriAP(l,CLKnCiD,0,S)s 
ENABLE (1); 

PSIDISnS(l,1000/G0)i COMflENT 1/G0 of a second — 

closest to the nay this norks at SU-AI; 


10.4 TENEX implfmentation 

The following describes how TENEX SAIL handles its interrupts The SAIL initialization 
docs a SIR, setting up the tables to external integers LEVTAB and CUNTAB, then does an EIR 
to turn on the interrupt system. PSIMAP fills the appropriate CHNTAB location with XUD 
LEV,LEVnOU, where LEVROU is the address of the routine that handles the interrupts for level 
LEV. LEVROU saves the accumulators in blocks PSIACS, PS2ACS, and PS3ACS, which are 
external integers, for levels I through 3 respectively. Thus, for a level 3 interrupt, accumulator x 
can be accessed by the expression: 
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riEriORY[LXATION(PS3ACS) ♦ x) 

where PS3ACS is an external integer. The PC can be obtained by reading the LEVTAB address 
with the RIR JSYS, as deKribed in (2]. 

ENABLE and DISABLE do AlC and DIC JSYSes respectively, and ATI and DTI do the 
ATI and DTI JSYSes. The user ran use such routines as RTIW and STIW to access the 
interrupts as described in the JSYS manual. 


10.} Interrupt Functions 

The following dcsciihes the routines that are available. Note that PSICHAN always refers to 
a TEN EX pseudo intm upt function. 

INTMAP(r5/C«/fA/. ROUTINE. CALLING! BLOCK) 

This is the same function as described in the SAIL manual [?]. It is equivalent to calling 
PSIMAP with the fourth argument a ?, for interrupt level 3. PSIMAP was added to allow the 
TEN EX SAIL user the ability to use all three levels. 

PSIMAP(P5/rW/lA/. ROUTINE. CALLINC/BLOCK. LEVEL) 

PSICHAN IS a number of a TENEX pseudo-interrupt channel. ROUTINE is executed at 
interrupt level LEVEL. If the interiupt is deferred, then CALLINC/BLOCK is an AOBJN pointer 
to the block that says what to do when the deferred code is actually processed later, as more fully 
described in [3], under the function INTMAP. PSIMAP is like INTMAP except that the LEVEL 
argument has been added. 

\miiET{PROCESSIITEM. ARGUMENT) 

Sprouts the INTPRO process for deferred interrupts, as in [3). 

EUABIKPSICHAN) 

Turns on PSICI IAN with the AlC JSYS. 

DlSABLEiPSICHAN) 

Turns off PSICHAN with the DIC JSYS. 

ATUPSICHAN.CODE) 

Does the ATI JSYS, associ.iting CODE with PSICHAN. CODE is not necessarily an ASCII 
character code, but it always is for control-A through control-Z. See [2] 


DTKCODE) 
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Docs the DTI JSYS for CODE. 

DFRINT 

The deferring routine, executed at interrupt level. See [3J. 

DFRINI 

See [3]. 

INTTHL(5/Z£) 

See [3]. 

CLKMOD 

See [3]. 

PHimmHiPSlCHAN. MSTIME) 

As described above, creates an inferior fork that initiates an interrupt on PSICHAN every 
MSTIME milliseconds. 

PSIRIINTM(P5/C7y>4/V. MSTIME) 

As described above, creates an inferior fork that initiates an interrupt on PSICHAN every 
time the current fork accumulates MSTIME milliseconds of runtime. 

KPSITIME(PSICHAN) 

Turns off any timing internipt on PSICHAN that may have been set up by PSITIME. 

ACI - mWiPSICHAN. X9AC2) 

Does the RTIW JSYS on PSICHAN. Accumulator I is the value of the call, accumulator 2 
is returned in AC2. 

STIVHPSICHAN. ACI. AC2) 

Does the STIW JSYS on PSICHAN. ACI and AC2 go into accumulators 2 and 3. 

ST/<n/S -CTRPW(fO«A:) 

The trap status of FORK is returned, using the CTRPW JSYS. 


II Imfflemrntalion of TENEX SAIL 
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The TENEX SAIL system is produced by a fairly complicated process, starting with many 
files and bootstraps. The entire process is detailed in TELLEM. the SAIL implemcnter’s guide. 

It should not however be necessary to go through this process since a complete set of 
standard TENEX .SAV and REL files for a recent version will be available from the Stanford 
Artificial Intelligence Prnjrrt, eithrr on tape or over the ARPA network. The version currently 
available will run on TENEX version 1.31. 

A complete TENEX SAIL system consists of the following files, listed by the directories on 
which they should reside. Note that a directory <SAIL> is required. Currently the total sue is 
about 150 pages of disk space. 


<SU05Y5> 

SAIL. SAV 
LOUISA. REL 


<SAIL> 


T-n-SAlSGm.SAV 

30PS3.0PS 

HLBSAm.REL 

LIBSAm.REL 

BKTBL.BKT 

UOOT.SAV 


SSAVEcI coiapi ler 

loader bootstrap 

goes on whichever directory 

compatibility believes to be SYSi 


third segment, where m.n is the 
version and subversion number 
START ICOOE opcode table, created 
by riAKTAB.TNX 
I ibrary 
I ibranj 

standard break table file 
version of UDOT for SAIL 
includes single-stepping 
instructions 


It should be straightforward to obtain and install these files without any reassembly. The sources 
for TENEX SAIL are available from Stanford or the author. 


II. I Com pllf-Timf Corf Map 

At compile time, there will usually be four segments in core. The impure data starts at IHO; 
the SAIL compiler starts at about iOOOOO and ends at about 450000; the opcode table, if needed, 
runs from about 600000 to 604000, the runtime system runs from 640000 to 670000. In addition, 
UDDT runs at its customary 770000 to about 775000. 
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11.2 Runtime Core Ma/> 

Ac runtime for h SAIL-compiled piogram, there are generally three segments; imp'jre data 
starting at HO; |irogiam and |iiire data starling at <100000: the runtime system between 640000 and 
670000. In addition, pages fiVi ihroiigh 637 are reserved for buffers by the SAIL I/O system. In 
sonae cases these buffers will be PMAPped pages of DSK files. Additionally, UDDT, if loaded, 
will be between 77(K>00 and 773000. 
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List (>/ Runtime Routtnrs 


V irulUiilfs ifiulinrs namfti afttr ajsys. 
"r hJicutfS tfiufinfs from DEC SAIL. 


ARRYIN 17 

CTAD 23 

ARRYOUT 18 

CTFDB: 16 

ASNDo 15 

CTJKNo 12 

ATb 29 

CTJFNLo 12 


CTRPWo 30 


CTSTSo 15 

BKJFNo 16 

GTTYPo 22 

CALL! 9 

IDTIMo 23 

CFILK H 

INDEXFILE II 

CHARIN 18 

INPUT 18 

CHAROUT 17 

INTIN 18 

CHFDB:. 16 

INTMAP 29 

CLKMOD 30 

INTSET 29 

CLOSE! 7 

INTTBL 30 

CLOSFo H 

INTTY 22 

CLOSINI 7 


CLOSOI 7 


CVJFN 8 

JFNS: 15 


DELFi- M 

KPSITIME 30 

DELNF.^ H 


DEVSTo 16 


DEVTYPE 16 

LINOUT 17 

DFRINI 30 

LOOKUP! 6 

DFRINT 30 


DIRSTf 24 


DISABLE 29 

MTAPE! 7 

DSKIN 20 

MTOPRo 16 

DSKOUT 20 


DTh 29 


DVCHRo 16 

ODTIMo 23 


OPEN! 6 


OPENFo 13 

ENABLE 29 

OPENFILE 10 

ENTER! 6 

OUT 17 

ERSTR«. 21 



PBTINr:. 22 

CDSTSo 15 

PMAPo 23 

C ETCH AN! 8 

PSIUISMS 30 

CJINFo 23 

PSIMAP 29 

CNJFNo 12 

PSIRUNTM 3( 
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Pige 54 


RCHPTR 19 
REALIN 18 
RELDo 15 
RELEASE! 7 
RENAME! 6 
RFRSZ; 16 
RFCOC:. 21 
RFMOD» 21 
RFPTRo 20 
RLJFNo M 
RNAMFo 15 
RTIWo ?0 
RUNPRC 24 
RUNTMo 23 
RWDPTR 20 


SCH^ 'R 19 
SDSTS: '5 
SETCHAN 13 
SETINPUT I 
SETPL II 
SFCOCc 21 
SFMODo 21 
SFPTRo 20 
SINI 18 
SIZEFo 15 
STDBRK 18 
STDEVo 16 
STDIRo 24 
STIWc 30 
STPARo 22 
STSTSo 15 • 

STTYPo 22 
SWDPTR 20 


UNDELETE 14 
USETI! 7 
USETO! 7 


WORDIN 17 
WORDOUT 17 
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